<!DOCTYPE HTML>
<html>
<head>
  <title>jquery.mentionsInput</title>
  <meta http-equiv="content-type" content="text/html;charset=UTF-8"/>
  <meta http-equiv="X-UA-Compatible" content="chrome=1">
  <link href='https://fonts.googleapis.com/css?family=PT+Sans&subset=latin' rel='stylesheet' type='text/css'>
  <link href='assets/style.css' rel='stylesheet' type='text/css'>
  <link href='jquery.mentionsInput.css' rel='stylesheet' type='text/css'>

  <script src='https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js' type='text/javascript'></script>
  <script src='//cdnjs.cloudflare.com/ajax/libs/underscore.js/1.8.3/underscore-min.js' type='text/javascript'></script>
</head>
<body>

<div class="container">

<h1>jquery.mentionsInput</h1>

<p>
  <a>jquery.mentionsInput</a> is a small, but awesome UI component that allows you to "@mention" someone in a text message, just like you are used to on Facebook or Twitter.
</p>

<p>This project is written by <a href="http://twitter.com/auchenberg">Kenneth Auchenberg</a>, and started as an internal project at <a href="http://podio.com">Podio</a>, but has then been open sourced to give it a life in the community. </p>

<p><a href="https://twitter.com/share" class="twitter-share-button" data-url="http://podio.github.com/jquery-mentions-input/" data-via="auchenberg" data-lang="en">Tweet</a></p>

<h2>Examples</h2>

<p>Basic example (<a href="assets/examples.js">source</a>)</p>

<div class="examples">
  <textarea class='mention' placeholder='Try to mention me, by typing @ken'></textarea>
  <a class="button get-syntax-text">Get marked-up value</a>
  <a class="button get-mentions">Get mentions collection</a>
</div>


<p>AJAX example. (Getting data by AJAX, and filter in callback - <a href="assets/example2.js">source</a>)</p>

<div class="examples">
  <textarea class='mention-example2' placeholder='Try to mention me, by typing @ken'></textarea>
</div>

<h2>Download and source</h2>
<p>You can grab the latest source from the repository on GitHub by clicking here: <a href="https://github.com/podio/jquery-mentions-input">https://github.com/podio/jquery-mentions-input</a>.</p>

<h2>Getting started</h2>

<ol>
  <li>
    Add a script reference to jquery.mentionsInput.js:<br/>
    <pre>&lt;script src=&#39;jquery.mentionsInput.js&#39; type=&#39;text/javascript&#39;&gt;&lt;/script&gt;</pre>
  </li>
  <li>
    Add a bit of markup: <br/>
    <pre>&lt;textarea class=&#39;mention&#39;&gt;</pre>
  </li>
  <li>
    <p>Initialise the mentionsInput: <br/>
    <pre>
$('textarea.mention').mentionsInput({
  onDataRequest:function (mode, query, callback) {
    var data = [
      { id:1, name:'Kenneth Auchenberg', 'avatar':'http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif', 'type':'contact' },
      { id:2, name:'Jon Froda', 'avatar':'http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif', 'type':'contact' },
      { id:3, name:'Anders Pollas', 'avatar':'http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif', 'type':'contact' },
      { id:4, name:'Kasper Hulthin', 'avatar':'http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif', 'type':'contact' },
      { id:5, name:'Andreas Haugstrup', 'avatar':'http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif', 'type':'contact' },
      { id:6, name:'Pete Lacey', 'avatar':'http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif', 'type':'contact' }
    ];

    data = _.filter(data, function(item) { return item.name.toLowerCase().indexOf(query.toLowerCase()) > -1 });

    callback.call(this, data);
  }
});
    </pre>
    </p>

    <p>
      Bam, you are in business.
    </p>
  </li>
</ol>

<h2>Configuration</h2>
<p>jquery.mentionsInput does have a number of extra configuration options which you may change to customise the way it behaves.</p>

<p>The meaning of the options and their default values are listed below. </p>

<table>
  <tr>
    <td><b>onDataRequest</b></td>
    <td><tt>function(mode, query, callback)</tt></td>
    <td class="definition">
      This function is a callback function which is used to provide data for the autocomplete. When a search starts
      this function is called with following arguments: 'search', the query (what's been typed), and a callback function which needs to be called inside onDataRequest with a data collection to be searched on as a first argument.
    </td>
  </tr>
  <tr>
    <td><b>triggerChar</b></td>
    <td><tt>@</tt></td>
    <td class="definition">
      Trigger character which triggers the mentions search, when the character has been typed into the
      mentions input field.
    </td>
  </tr>
  <tr>
    <td><b>minChars</b></td>
    <td><tt>2</tt></td>
    <td class="definition">
      The minimum amount of characters after the trigger character necessary to perform a search.
    </td>
  </tr>
  <tr>
    <td><b>showAvatars</b></td>
    <td><tt>true&nbsp;|&nbsp;false</tt></td>
    <td class="definition">
      Toggles whether or not items within the autocomplete-dropdown will be rendered with an icon/avatar.
    </td>
  </tr>
  <tr>
    <td><b>classes</b></td>
    <td><tt>object</tt></td>
    <td class="definition">
      Object which contains classes used in the layout as key/value pairs.
    </td>
  </tr>
  <tr>
    <td><b>templates</b></td>
    <td><tt>object</tt></td>
    <td class="definition">
      Object which contains templates used to render the layout as key/value pairs.
    </td>
  </tr>
</table>

<h2>Methods</h2>

<p>jquery.mentionsInput does expose a number of public methods, you can call on an instance. </p>

<table>
  <tr>
    <td><b>init</b></td>
    <td></td>
    <td class="definition">
      Initialises the mentionsInput component on a specific element.
    </td>
  </tr>
  <tr>
    <td><b>reset</b></td>
    <td></td>
    <td class="definition">
      Resets the component, clears all mentions.
    </td>
  </tr>
  <tr>
    <td><b>val(callback)</b></td>
    <td></td>
    <td class="definition">
      An async method which accepts a callback function and returns a value of the input field (including markup) as a first parameter of this function. <br/><br/> This is the value you want to send to your server.
    </td>
  </tr>
  <tr>
    <td><b>getMentions(callback)</b></td>
    <td></td>
    <td class="definition">
      An async method which accepts a callback function and returns a collection of mentions as hash objects as a first parameter.
    </td>
  </tr>
</table>

<h2>Query data structure</h2>

<p>When the component is preforming a "query" on the data specified through the onDataRequest-callback, it's expecting a specific data structure to be returned. </p>
<pre>
{
  'id'    : 1,
  'name'  : 'Kenneth Auchenberg',
  'avatar': 'http://cdn0.4dots.com/i/customavatars/avatar7112_1.gif',
  'icon'  : 'icon-16 icon-person',
  'type'  : 'contact'
}
</pre>

<p>"avatar" property is a URL used for image avatars when  "showAvatars"-option is enabled </p>
<p>"icon" property is a className used for avatars when "showAvatars"-option is disabled</p>
<p>"type" property specifies an object type which is used in the marked-up version of the mentions result</p>


<h2>Markup format</h2>
<p>When mentions are being added to the input, a marked-up version of the value is generated, to allow the mentions to be extracted, parsed and stored later. </p>
<pre>
  This is a message for @[name](type:id)
</pre>
<p>Like:</p>
<pre>
  This is a message for @[Kenneth Auchenberg](contact:1)
</pre>


<h2>Browser support</h2>
<p>jquery.mentionsInput has been tested in Firefox 6+, Chrome 15+, and Internet Explorer 8+. </p>
<p>Please let us know if you see anything weird. And no, we will no make it work for older browsers. Period. </p>

<h2>Dependencies</h2>
<p>jquery.mentionsInput is written as a jQuery extension, so it naturally requires <a href="http://jquery.com">jQuery (1.6+)</a>. In addition to jQuery, it also depends on <a href="http://documentcloud.github.com/underscore/">underscore.js (1.2+)</a>, which is used to simplify stuff a bit.</p>

<p>The component is also using the new HTML5 "input" event. This means older browsers like IE8 need a polyfill which emulates the event (it is bundled).</p>

<p>The component itself is implemented as a small independent function, so it can easily be ported to frameworks other than jQuery. </p>

<p>Furthermore all utility functions have been centralized in the utils-object, which can be replaced with references if you already got functions like htmlEncode, etc. </p>

<p>To make the component grow and shrink to fit it’s content, you can include <a href="http://www.unwrongest.com/projects/elastic">jquery.elastic.js</a></p>

<h2>License</h2>
<p>MIT License - <a href="http://www.opensource.org/licenses/mit-license.php">http://www.opensource.org/licenses/mit-license.php</a></p>

<h2>Change Log</h2>

<p>
  <b class="header">1.0.1</b><br/>
  <ul>
    <li>Removed elastic-option since it wasn't really working without it. <a href="https://github.com/podio/jquery-mentions-input/issues/1"> https://github.com/podio/jquery-mentions-input/issues/1</a>)</li>
    <li>Fixed issue with space on search queries. (<a href="https://github.com/podio/jquery-mentions-input/issues/24"> https://github.com/podio/jquery-mentions-input/issues/24</a>)</li>
  </ul>
</p>

<p>
  <b class="header">1.0.0</b><br/>
  <ul>
    <li>Initial release.</li>
  </ul>
</p>

  </div>

  <script src='lib/jquery.events.input.js' type='text/javascript'></script>
  <script src='lib/jquery.elastic.js' type='text/javascript'></script>
  <script src='jquery.mentionsInput.js' type='text/javascript'></script>
  <script src='assets/examples.js' type='text/javascript'></script>
  <script src='assets/example2.js' type='text/javascript'></script>

  <script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src="//platform.twitter.com/widgets.js";fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");</script>

  <script type="text/javascript">

    var _gaq = _gaq || [];
    _gaq.push(['_setAccount', 'UA-27763738-1']);
    _gaq.push(['_trackPageview']);

    (function() {
      var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
      ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
      var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
    })();

  </script>

</body>
</html>